home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / u_man / cat3 / OpenGL / ogldebug.z / ogldebug
Encoding:
Text File  |  2001-04-17  |  11.2 KB  |  331 lines
  1.  
  2.  
  3.  
  4. ooooggggllllddddeeeebbbbuuuugggg((((3333GGGG))))                   OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee                   ooooggggllllddddeeeebbbbuuuugggg((((3333GGGG))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ooooggggllllddddeeeebbbbuuuugggg - OpenGL debugging utility
  10.  
  11.  
  12.  
  13. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  14.      ooooggggllllddddeeeebbbbuuuugggg [options]
  15.  
  16.  
  17. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  18.      ooooggggllllddddeeeebbbbuuuugggg is a development tool that allows you to examine OpenGL calls
  19.      generated by an application.
  20.  
  21.      ogldebug command line options:
  22.  
  23.      -display <display>          Set the display for the user interface of
  24.                                  ogldebug. ogldebug will use $DISPLAY if
  25.                                  -display is not specified
  26.  
  27.      -appdisplay <display>       Set the display for the application.
  28.  
  29.      -glsplay <gls trace file>   Play back a gls trace file recorded by
  30.                                  ogldebug. Note that a gls trace file is not
  31.                                  standard c.
  32.  
  33.      -gls2c <gls trace file>     Convert a gls trace file to a c code snippet.
  34.                                  Output is to stdout.
  35.  
  36.      -gls2x <gls trace file>     Convert a gls trace file to a compile-able X
  37.                                  Window System program. Output is to stdout.
  38.  
  39.      -gls2glut <gls trace file>  Convert a gls trace file to a compile-able
  40.                                  GLUT program. Output is to stdout.
  41.  
  42.      To debug an OpenGL application, enter the command:
  43.  
  44.          ogldebug <ogldebug options if any> <o32 app> <app options if any>
  45.          ogldebug32 <ogldebug options if any> <n32 app> <app options if any>
  46.          ogldebug64 <ogldebug options if any> <64 app> <app options if any>
  47.  
  48.      ogldebug becomes active when the application makes its first OpenGL call.
  49.      Each ogldebug represents a different application process. If the
  50.      application uses fork, sproc or pthread, then multiple instances of
  51.      ogldebug may appear.
  52.  
  53.      The main window is described below:
  54.  
  55.      At the top are two fields that display the application's process ID and
  56.      current OpenGL context.
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ooooggggllllddddeeeebbbbuuuugggg((((3333GGGG))))                   OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee                   ooooggggllllddddeeeebbbbuuuugggg((((3333GGGG))))
  71.  
  72.  
  73.  
  74.      Below is the current OpenGL call to be executed.
  75.  
  76.      Below is a field that displays information/status from ogldebug.
  77.  
  78.      Below is a row of control buttons:
  79.  
  80.      Halt      Stop at the next OpenGL call.
  81.  
  82.      Continue  Continue execution of application. No updates will occur as
  83.                long as the application is running.
  84.  
  85.      Step      Single step to the next OpenGL call.
  86.  
  87.      Skip      Skip the current call and step to the next one.
  88.  
  89.      For both Step and Skip, if the application is running, ogldebug will halt
  90.      at the next OpenGL call.
  91.  
  92.      Below is a series of user option toggle buttons:
  93.  
  94.      Check for GL warning/error  Calls glGetError after every OpenGL call to
  95.                                  check for errors. Note that glGetError cannot
  96.                                  be called between glBegin and glEnd pairs. If
  97.                                  an error is detected, glGetError is called
  98.                                  repeatedly.
  99.  
  100.      Control drawing             Allows the user to inspect drawing in
  101.                                  progress (force front buffer rendering). Also
  102.                                  allows the user to control drawing speed.
  103.  
  104.      History                     Save calls to history. Use the adjacent Setup
  105.                                  button to select which calls to include into
  106.                                  history as well as control additional history
  107.                                  information.
  108.  
  109.      Break on GL calls           Halt on OpenGL calls. Use the adjacent Setup
  110.                                  button to select which calls to halt on.
  111.  
  112.      Break on SwapBuffers        Halt on SwapBuffers. This is not a core
  113.                                  OpenGL function but a windowing system
  114.                                  dependent call.
  115.  
  116.      Skip GL calls               Skip selected OpenGL calls. Use the adjacent
  117.                                  Setup button to select which calls to skip.
  118.  
  119.      Note that the History, Break on GL calls and Skip GL calls setup panels
  120.      allow you to save/recall up to three custom set/unset groups at a time.
  121.      Also, these panels support the standard shift, control, shift-control
  122.      keystrokes for multiple item selection/deselection. For convienence,
  123.      glFlush is selected by default for Break on GL calls but is not active
  124.      unless Break on GL calls is toggled on.
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ooooggggllllddddeeeebbbbuuuugggg((((3333GGGG))))                   OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee                   ooooggggllllddddeeeebbbbuuuugggg((((3333GGGG))))
  137.  
  138.  
  139.  
  140.      The menu items are described below:
  141.  
  142.      Under the File menu:
  143.  
  144.      About ogldebug        Shows ogldebug version number.
  145.  
  146.      Save Configuration    Saves current configuration to a file. The default
  147.                            file name is ogldebug.cfg.
  148.  
  149.      Recall Configuration  Recalls configuration from a file. The default file
  150.                            name is ogldebug.cfg.
  151.  
  152.      Quit                  Exits ogldebug.
  153.  
  154.      Under the Command menu, you will find duplicate functionality of the
  155.      control buttons. This provides you with keyboard equivalence.
  156.  
  157.      Under the Options menu:
  158.  
  159.      Call Count       Brings up a panel with counts for OpenGL, GLU, GLX and
  160.                       GLC calls. You can show all or only non-zero calls.
  161.  
  162.      Call History     Brings up a panel with a history of OpenGL calls. The
  163.                       history is in the form of a gls trace.
  164.  
  165.      Display List     Brings up a panel with information about the
  166.                       application's display lists. You can show all or only
  167.                       non-empty display lists.
  168.  
  169.      Primitive Count  Brings up a panel with primitive counts for the
  170.                       application.
  171.  
  172.      State            Brings up a panel with state information. You can show
  173.                       all or only non-default state. You can also take a
  174.                       snapshot of the current state for later comparison. Note
  175.                       that state cannot be queried between glBegin and glEnd
  176.                       pairs.
  177.  
  178.      Window           Brings up a panel with information on application's
  179.                       windows.
  180.  
  181.      Under the Reference menu:
  182.  
  183.      Enumerates  A reference to the OpenGL enumerant values.
  184.  
  185.  
  186. NNNNOOOOTTTTEEEESSSS
  187.      Here is an example of how to get a gls trace of an application:
  188.  
  189.      1) ogldebug <application>. Make sure you match ogldebug (ogldebug,
  190.         ogldebug32 or ogldebug64) with your application's compiled type.
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. ooooggggllllddddeeeebbbbuuuugggg((((3333GGGG))))                   OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee                   ooooggggllllddddeeeebbbbuuuugggg((((3333GGGG))))
  203.  
  204.  
  205.  
  206.      2) Run until application has passed the point of interest. You may want
  207.         to ensure that a complete frame has been capture by breaking on
  208.         glFlush or SwapBuffer.
  209.  
  210.      3) Select Call History from the Information menu. You will be first
  211.         presented with a panel to select which OpenGL context of which you
  212.         want a gls trace. There may be more then one OpenGL context available,
  213.         depending on the application.
  214.  
  215.      4) Select the OpenGL context you want a gls trace of. A Call History
  216.         panel will appear. You now can save a gls trace file. Note that if the
  217.         call history is large (slow to load), you have the option of directly
  218.         saving to a file.
  219.  
  220.      A gls trace is meant to be pure OpenGL and window-system independent.
  221.      However, comments have been added to indicate when GLX, GLU and GLC calls
  222.      were made. Any OpenGL calls made from within these higher level calls are
  223.      indented. Performance hints are also included.
  224.  
  225.      At this point, you may play back the gls trace file with the -glsplay
  226.      option or convert the gls trace file to various c files with the -gls2c,
  227.      -gls2x and -gls2glut options. Any comments or hints in the gls trace file
  228.      are removed during the conversion.
  229.  
  230.      You may want to use the No History feature for large application such as
  231.      Performer. If you need to run the application to a particular point and
  232.      do not care about the call history until that point, turn on No History
  233.      to speed things up.
  234.  
  235.  
  236. FFFFIIIILLLLEEEESSSS
  237.      ogldebug has two parts: a user interface control application (ogldebug)
  238.      and a special library that sits between an application and libGL.so
  239.      (libogldebug.so).
  240.  
  241.      ogldebug should be in a directory that is included in your $PATH
  242.      environment variable (normally /usr/sbin). libogldebug.so must be in the
  243.      same directory as libGL.so (normally /usr/lib).
  244.  
  245.      At startup, ogldebug will look for the configuration file ./ogldebug.cfg
  246.      then $HOME/ogldebug.cfg then $HOME/.ogldebug.cfg.
  247.  
  248.      If ogldebug should quit abnormally, it may leave files behind. ogldebug
  249.      stores all of it's work files in a directory named OGLDEBUG_<unique ID>.
  250.      The default location for this work directory is /tmp. However, ogldebug
  251.      will use $TMPDIR if set.
  252.  
  253.      /usr/sbin/ogldebug
  254.      /usr/sbin/ogldebug32
  255.      /usr/sbin/ogldebug64
  256.      $ROOT/usr/lib/libogldebug.so
  257.      $ROOT/usr/lib32/libogldebug.so
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. ooooggggllllddddeeeebbbbuuuugggg((((3333GGGG))))                   OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee                   ooooggggllllddddeeeebbbbuuuugggg((((3333GGGG))))
  269.  
  270.  
  271.  
  272.      $ROOT/usr/lib64/libogldebug.so
  273.      /usr/share/catman/u_man/cat3/OpenGL/ogldebug.z
  274.  
  275.  
  276. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  277.      ggggllllssssiiiinnnnttttrrrroooo(3G)
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.